/**
 * @file planner_interface.hpp
 * @brief 路径规划器接口的头文件
 * 
 * 该文件定义了路径规划器的通用接口，所有具体的规划算法都应该实现这个接口。
 * 提供了规划器的基本功能，如初始化、设置地图和执行规划等。
 */

#ifndef PLANNER_INTERFACE_HPP
#define PLANNER_INTERFACE_HPP

#include <ros/ros.h>
#include <nav_msgs/Path.h>
#include <nav_msgs/OccupancyGrid.h>
#include <geometry_msgs/PoseStamped.h>
#include <string>
#include <memory>

namespace auto_navigation {
namespace planning {

/**
 * @class PlannerInterface
 * @brief 路径规划器的抽象接口类
 * 
 * 该类定义了路径规划器的通用接口，所有具体的规划算法都应该继承并实现这个接口。
 * 提供了规划器的基本功能，如初始化、设置地图和执行规划等。
 */
class PlannerInterface {
public:
    /**
     * @brief 构造函数
     * @param name 规划器名称
     */
    PlannerInterface(const std::string& name) : name_(name) {}
    
    /**
     * @brief 虚析构函数
     */
    virtual ~PlannerInterface() {}
    
    /**
     * @brief 获取规划器名称
     * @return 规划器名称
     */
    std::string getName() const { return name_; }
    
    /**
     * @brief 初始化规划器
     * @param nh ROS节点句柄
     * @return 是否成功初始化
     * 
     * 从参数服务器读取规划器所需的参数，并进行初始化
     */
    virtual bool initialize(ros::NodeHandle& nh) = 0;
    
    /**
     * @brief 设置地图
     * @param map 占用栅格地图
     * @return 是否成功设置
     * 
     * 设置规划器使用的栅格地图
     */
    virtual bool setMap(const nav_msgs::OccupancyGrid& map) = 0;
    
    /**
     * @brief 规划路径
     * @param start 起始位姿
     * @param goal 目标位姿
     * @param path 输出的路径
     * @return 是否成功规划
     * 
     * 在栅格地图上规划从起点到终点的路径
     */
    virtual bool plan(const geometry_msgs::PoseStamped& start,
                     const geometry_msgs::PoseStamped& goal,
                     nav_msgs::Path& path) = 0;
    
protected:
    std::string name_;  ///< 规划器名称
};

// 使用智能指针管理规划器
typedef std::shared_ptr<PlannerInterface> PlannerInterfacePtr;

} // namespace planning
} // namespace auto_navigation

#endif // PLANNER_INTERFACE_HPP 